Session management functions
This section describes PKCS#11 session management functions.
Note
ProtectToolkit-C allows an application to have concurrent sessions with more than one token. It is also possible for a token to have concurrent sessions with more than one application.
The ProtectServer 3 HSM supports up to 65534 concurrent sessions.
C_OpenSession
This function operates as specified in PKCS#11 with the following exceptions:
-
The Notify parameter is ignored.
-
The
CKF_SERIAL_SESSION
flag is ignored. -
PKCS#11 states “If the application calling
C_OpenSession
already has a R/W SO session open with the token, then any attempt to open a R/O session with the token fails with error codeCKR_SESSION_READ_WRITE_SO_EXISTS”
this is not enforced with ProtectToolkit-C.
Synopsis
C_OpenSession(
CK_SLOT_ID slotID,
CK_FLAGS flags,
CK_VOID_PTR pApplication,
CK_NOTIFY Notify,
CK_SESSION_HANDLE_PTR phSession
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, the first C_OpenSession() call selects a random token from the list of available WLD tokens to open the session with. Subsequent C_OpenSession() calls, randomly select a token from those with the least number of sessions.
If successful, a WLD session handle is returned. The WLD session handle is internally mapped to the appropriate HSM token and session handle.
If unsuccessful, for ANY reason, another token is chosen and ProtectToolkit-C retries to open a session utilizing this token. This is repeated until either a session is opened successfully or no more tokens are available.
If the HSM token used did not result in a session opening successfully for one of the following error conditions, the token will no longer be considered for WLD for the life of the application:
-
CKR_GENERAL_ERROR
-
CKR_DEVICE_ERROR
-
CKR_MESSAGE_ERROR number space (SafeNet vendor defined)
Note
When the any of the above error conditions are detected C_OpenSession() will not return the associated error code as ProtectToolkit-C will retry to open a session using another token until all tokens are exhausted. If there are no tokens available the error CKR_TOKEN_NOT_PRESENT are returned.
C_CloseSession
This function operates as specified in PKCS#11 with the following exception:
- ProtectToolkit-C has no capability to “eject” the token from its reader.
Synopsis
C_CloseSession(
CK_SESSION_HANDLE hSession
);
C_CloseAllSessions
This function operates as specified in PKCS#11 with the following exception:
- ProtectToolkit-C has no capability to “eject” the token from its reader. Further, this function will perform a “logout” on each token if necessary.
Synopsis
C_CloseAllSessions(
CK_SLOT_ID slotID
);
C_GetSessionInfo
This function operates as specified in PKCS#11 with the following exception
- Any non-zero ulDeviceError value is cleared by this operation.
Synopsis
C_GetSessionInfo(
CK_SESSION_HANDLE hSession,
CK_SESSION_INFO_PTR pInfo
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, the following WLD-specific information is returned in the CK_SESSION_INFO structure:
- SlotID
-
The Slot Number specified for the virtual WLD Slot in environment variables ET_PTKC_WLD_SLOT_n. Refer to ProtectToolkit-C administration.
- Flags
-
The CKF_WLD_SESSION bit is set to indicate that it is a WLD Session.
C_GetOperationState
C_GetOperationState obtains a copy of the cryptographic Operation State for a session, encoded as a string of Bytes. hSession is the session’s handle; pOperationState points to the location that receives the state; pulOperationStateLen points to the location that receives the length in bytes of the state.
ProtectToolkit-C implements a subset of the full PKCS#11 specification - only the current Message Digest state and object attribute search state can be saved and restored. This means that the current encryption, decryption, signing and verification states are not saved by this function.
The state need not have been obtained from the same session (the “source session”) as it is being restored to (the “destination session”). However, the source session and destination session should have a common session state (for example, CKS_RW_USER_FUNCTIONS), and should be with a common token. Message digest operation states can be carried across logins but not across different Cryptoki implementations.
Synopsis
C_GetOperationState(
CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pOperationState,
CK_ULONG_PTR pulOperationStateLen
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function is not supported and will return the error CKR_FUNCTION_NOT_SUPPORTED.
C_SetOperationState
C_SetOperationState restores the cryptographic Operations State of a session from a string of bytes obtained with C_GetOperationState. ProtectToolkit-C implements a subset of the full PKCS#11 specification - only the current Message Digest state and object search state can be saved and restored.
hSession is the session’s handle; pOperationState points to the location holding the saved state; ulOperationStateLen holds the length of the saved state; hEncryptionKey and hAuthenticationKey must be zero.
The state need not have been obtained from the same session (the “source session”) as it is being restored to (the “destination session”). However, the source session and destination session should have a common session state (for example, CKS_RW_USER_FUNCTIONS
), and should be with a common tokenMessage digest operation states can be carried across logins but not across different Cryptoki implementations.
If C_SetOperationState is supplied with a saved cryptographic Operations State, which it determines is not a valid saved State, it fails with the error CKR_SAVED_STATE_INVALID
. Invalid States include cryptographic Operations State from a session with a different session state and cryptographic Operations State from a different token.
C_SetOperationState can successfully restore the message digest Operations State to a session, even if that session has an active message digest or object search operation when C_SetOperationState is called. The ongoing operations are abruptly cancelled. However if the saved state did not contain an active message digest operation and the current session does, then the C_SetOperationState function will have no effect on the current operation.
Synopsis
C_SetOperationState(
CK_SESSION_HANDLE hSession,
CK_BYTE_PTR pOperationState,
CK_ULONG ulOperationStateLen,
CK_OBJECT_HANDLE hEncryptionKey,
CK_OBJECT_HANDLE hAuthenticationKey
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, this function is not supported and will return the error CKR_FUNCTION_NOT_SUPPORTED.
C_Login
This function operates as specified in PKCS#11 with the following exceptions:
-
If the security mode NoClearPINs is enabled, then the PIN value is encrypted by the host library before it is supplied to the module.
-
To negate a brute force attack on the PIN, after the third failed attempt, a delay is imposed (incrementing in multiples of 5 seconds) until the next presented PIN is checked.
For example, after the third failed attempt, the device imposes a delay of 15 seconds, after the fourth the delay is 25=10 seconds, after the fifth, the delay is 3*5=15 seconds, and so on.
If a PIN presentation occurs before the delay period has expired, the attempt fails with CKR_PIN_LOCKED.
Synopsis
C_Login(
CK_SESSION_HANDLE hSession,
CK_USER_TYPE userType,
CK_CHAR_PTR pPin,
CK_ULONG ulPinLen
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, the login state is replicated across all tokens in user slots associated with the same WLD slot. For example, if an application has 3 sessions, across 3 HSMs, with one session on each HSM then any change in the login state in one session, will result in the session on the other 2 HSMs being changed to the same session state.
C_Logout
This function operates as specified in PKCS#11.
Synopsis
C_Logout(
CK_SESSION_HANDLE hSession
);
Operation in WLD Mode
When ProtectToolkit is configured to operate in WLD mode, the login state is replicated across all tokens in user slots associated with the same WLD slot. For example, if an application has 3 sessions, across 3 HSMs, with one session on each HSM then any change in the login state in one session, will result in the session on the other 2 HSMs being changed to the same session state.